Repository navigation
feat(cli): cloudhal export writes a site archive (#47, step 2) - #130
Merged
3 commits merged intoOct 25, 2026
Merged
3 commits merged into
3 commits merged into
Conversation
importSite inserted bundle.project as given when the target lacked it, so a crafted bundle could plant any projects row. The row must now be the site node's project, a valid Project, with id and rev matching its body. Covers pull, the admin bundle route behind push, and the coming `cloudhal import`. Refs #47 Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: Madraka <[email protected]>
RFC-0039 rollout step 2. `cloudhal export [--out <file>] [--site <id>] [--no-media] [--latest-only]` writes one site of the local project to a .cloudhal file: exportSite's bundle as NDJSON parts, media streamed from the local blob store and verified, and the takedown ledger. - Default name <site-slug>-<YYYYMMDD>.cloudhal, dated by the newest row it holds (never the clock), so an unchanged site exports identically. A file at the default name is replaced only by the same archive; --out replaces any. - --site takes a site listed in cloudhal.json sites; --site, --no-media and --latest-only are refused on every other command. - --latest-only keeps the published and the latest snapshot and what they need; refused while a field operation is unfinished. - Ctrl-C and SIGTERM remove the partial file. - The summary lists what an archive never holds (RFC-0039 §4) and that its history names who made each change. archive-bundle.ts and archive-reassemble.ts convert a bundle to archive content and back (step 3's import reuses the second); the tests check the round trip deep-equals exportSite's bundle. Refs #47 Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: Madraka <[email protected]>
Madraka
enabled auto-merge
October 25, 2026 21:43
… test The seed's clock moves in 20 ms steps, so other snapshots can already share the newest one's created_at; the test picked the first earlier row with a larger id instead of the largest, and failed when another tied row sorted after it (CI on #130). Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: Madraka <[email protected]>
5 tasks done
5 tasks done
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
This is step 2 of RFC-0039's rollout for #47:
cloudhal export [--out <file>] [--site <id>] [--no-media] [--latest-only]. It writes one site of the local project to a.cloudhalfile, using the container from #129.exportSite's bundle written as NDJSON parts (project.json, nodes, snapshots, and the blobs those snapshots reference). Media streams from the local blob store and is verified against its SHA-256. The takedown ledger is included; taken-down bytes never are.<site-slug>-<YYYYMMDD>.cloudhal. The date is the newest row timestamp in the archive, not the clock, so an unchanged site exports to identical bytes (invariant 7 as amended in feat(cli): site archive container for export and import (#47, step 1) #129). If a file with the default name already exists, it is replaced only by the same archive. A different one (an edit later the same day, other flags, a deletion) is refused with a message asking for--out, so a full backup is never silently overwritten by a--no-mediaor--latest-onlyexport.--outreplaces whatever file is there.--site <id>: exports another site, which must be listed incloudhal.jsonsites.--site,--no-mediaand--latest-onlyare refused on every other command. They live in the sharedOPTIONStable, so without that checkcloudhal push --site xwould have parsed and acted on the main site.--latest-only: keeps only the published and latest snapshots (store.latestSnapshot), plus the blobs and media those snapshots and the current nodes need. It is refused while a field operation is unfinished, because it would drop that operation'sbeforesnapshot.archive-bundle.tsconverts a bundle to archive content.archive-reassemble.tsconverts archive items back to exactly theSiteBundlethatexportSitereturns, with strict row checks and fixed error messages that never echo untrusted input. Step 3 (cloudhal import) reuses the second.bundle.media'smediaTypeis rebuilt from the asset bodies, the same wayexportSitebuilds it.fix(core-ts)(separate commit, its own changeset):importSitenow checks a bundle's project row. It must be the site node's project, a validProject, and itsidandrevmust match its body. Before this, a crafted bundle (pull, the admin bundle route, the coming import) could plant anyprojectsrow.Known limitation (stated in the module doc): graph rows are held in memory, because
exportSitereturns a whole bundle andimportSite's single batch already limits a site to about 1000 nodes. Media bytes stream.For the owner
uploadedBy, block provenance, translation reviews and takedownbycarry user or agent ids, and mostly display names. Push and pull carry the same data. The sentence "People and personal data never leave in a file by accident" is therefore not exact. The help text and summary now say this openly. Should the RFC be amended, or shouldexportgain an option to strip actor names? This PR leaves the Accepted RFC text alone.Verification (local)
vitest run archive- export-cli cli-commandsinpackages/cli: 9 files, 157 tests. They cover:exportSite, and two exports give identical bytes;--no-media,--latest-only(including two snapshots with the samecreated_at, and an unfinished field operation), and--site(listed and unlisted);.partial;packages/core-ts:sync,multi-site,site-time-zoneandentry-gatestests (28) pass with the project-row check.pnpm size:checkpass.tar -tzvflistsmanifest.json,project.json, the three parts and one media file, all0 0, 1970,-rw-r--r--.Checklist
pnpm checkandcargo test --workspacepass locally. I ran the pieces that cover this change; CI runs the full set, including the Cloudflare push/pull suites that exercise the project-row check..changeset/site-archive-export.md(@cloudhal/clipatch) and.changeset/bundle-project-row.md(@cloudhal/core-tspatch).git commit -s, DCO)help.tsis updated, and the docs site's CLI reference is generated from it. The guide comes in step 5.Refs #47
🤖 Generated with Claude Code